COMMENT ⊗   VALID 00010 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	.Rst= Rastor font file
C00006 00003	Vocabulary - needs work
C00007 00004	File Mark
C00009 00005	Preamble
C00014 00006	the preamble- discussion
C00019 00007	Directory and Rasters
C00024 00008	    More on the directory and bit representation- needs update
C00029 00009	    Still more...
C00032 00010	Naming font files, Other Programs and Sources
C00035 ENDMK
C⊗;
.Rst= Rastor font file

This document describes the format of the  Rst file as of August 1,  1981.
This is version 0.  Please send comments and/or suggestions to RAS.   This
file was last updated January 28, 1982 by RAS.

The Rst  format was  designed to  be easy  to use,  compact and  complete.
Growing from  Les Earnest's  FNT  and Dave  Fuchs'  VNT formats,   it  was
developed to be especially suited for use with Impress files.

Currently Rst files are used by  the ImPrint-10 printer.  Each  is  device
specific  since  each  contains rasterized  pictures.   Printed,  a   font
specified by  a  given  Rst  file  will vary  in  size  depending  on  the
resolution of the printer; its quality may vary depending on the thickness
of a printed pixel (how well a printer focuses a dot).

MetaFont can create  Rst files.   At present  there are  no programs  that
convert between Rst files and  other formats.  The program RdRst  produces
an ascii textual description of an Rs file.

INFORMAL DESCRIPTION 
An Rst  file contains  a  description of  a font  suitable  for use  on  a
specific output  device.   The  images  of  characters  are  described  by
sequences of bits that specify which pixels in a bounding rectangle should
be blackened.

An Rst file contains  the following sections:  File Mark, Preamble,  Glyph
Directory, Raster Data.   In the  beginning of the  file there  is a  file
mark, declaring the file to be an Rst file.  The Preamble is next,  giving
vital information about the font, such  as how many characters are in  it,
as well as nonessential information, such as who created the file.   Next,
the glyph directory contains the size of each glyph and a pointer into the
last section which contains the raster data for each glyph.

Rst files are not sufficient for typesetting, which requires TFM files for
information about  kerning  and  ligatures.  However,  Rst  files  contain
enough information to print listings nicely.

FORMAT DESCRIPTION 
Rst files are comprised of 8-bit bytes.  Often these are combined to  form
multiple bytes fields for  parameters.  On Sail, 4  bytes are packed  into
each 36-bit Sail word in the 32 high order (left) bits.  The high byte  is
the first byte in a word, the rightmost byte, the last.  The first byte in
the file is numbered zero.

There are four  parts to an  Rst file,  a font marker,  the preamble,  the
directory and the raster  section.  They occur in  this same order in  the
Rst file.

Vocabulary - needs work

glyph vs character vs symbol

pixel and bit

byte

two's complement

points

reference point

mag
designsize
space width

printing coordinates ↓→

rotation
advance directions and width

A FIX is an integer, equal to 2↑-20 points.  There are 72.27 points per
inch.  To convert a FIX integer, F,  to a real number of points, R:
    R← F / 2↑20;

% truncating divistion
File Mark

The file  mark is  8 bytes  long.  The  first four  bytes of  an Rst  file
contain the ascii letters "Rast", identifying the file type.

The next four bytes are currently unused, and contain zero.

Preamble

The preamble begins in the eighth byte of the Rst file with the number  of
bytes containing the rest of the preamble, followed by the file's  version
number.  The  file is  version  dependent.  Version  0  has 18  fields  of
information in at least 40 bytes.

A string is  represented as  a sequence of  8-bit bytes.   The first  byte
contains the number of bytes in the rest of the string.  Thus a string can
contain at most 255 characters, though most are only a few bytes long.

byt #bytes	description of each preamble field
--------------------------------------------------------------------------
8   2	The number of bytes in the Preamble, not including the two used
	in this field.
10  1	The version number, latest version is zero.
11  3   pointer to the glyph directory (greater than or equal to 46).

14  2   Character number of the first glyph in the font,  usually this is 0.
16  2   Character number of the last glyph in the font, usualy this is 127.

18  4   The magnification, in 1/1000's.  For example, an unmagnified font will
	have magnification 1000, a font that is twice as big as its designsize
	will have magnification 2000 (0 mag should be interpreted as 1000).
22  4   The designsize (D) of the font, in FIXes.  If the font is not magnified,
	this will be the intended size of this font.  
26  4	The interline spacing for the font, in FIXes.  If this field is
	zero, try designsize*1.2
30  4   Space width.  The width of a good looking interword space, in fixes.
	If this parameter is zero, try designsize/1.2

34  2   Rotation of the font in (ccw, positive) degrees.  Normal fonts have 
	rotation 0; fonts to read while standing the page on its right edge
	have rotation 270.
36  1	Character advance direction relative to the font's rotation.  This
	tells where to place a "next character" on a "line of characters".
	0=to the right, 1=below, 2=to the left, 3=upward.  The English fonts
	have character advance direction 0, Chinese:1, Hebrew 2.
37  1	Line advance direction relative to the font's rotation.  This tells
	where to place a "next line of characters" on the page, relative to 
	the last line.  0=to the right, 1=below, 2=to the left, 3=upward.  
	The English fonts and Hebrew have line advance direction 1, Chinese:0.

38  4   A check identifier.  This is used with metafont files to associate an Rst
	file with a specific TFM file.  This ensures that the TFM and Rst are
	describing the same font.  If this field is zero, no check is to be done.
	(Note: One need not make the check, it is included to allow verification)

42  2   Resolution of the font in pixels/inch- 240 for the ImPrint-10.

44  var A font identifier string.

≥45 var A face-type encoding string.

≥46 var Output device string.

≥47 var Creator string.  A verification program might check all the previous 
	fields for accuracy, but not this one.

the preamble- discussion

Note: the previous page is correct, in case of discrepancy

The first five fields,  size of the preamble,  version number, pointer  to
the glyph directory, character numbers of the first and last glyphs in the
font, must be correct for any Rst to be usable.

The next  field  is  the  magnification.   Though  the  magnification  can
presumably be obtained from the file name, it is included for verification
and to allow a magnification of greater

The magnification is needed in order to correctly precision than the  file
name might allow.  interpret the widths of the characters.  The widths  of
the characters at their  designsize are stored in  the directory.  If  the
font is at  magnification =  2.0, the characters  are twice  as big.   The
correct width of  a character then  is its given  width multiplied by  the
magnification.

The individual  character  widths  are  given  without  the  magnification
figured in  so  that a  printing  program can  substitute  a font  at  one
magnification for one at another magnification.   If TEX says an Rst  font
file at mag 2.4 is called for, but does not exist, but one at 2.5  exists,
the latter can be used.  The 2.5  characters will be printed, but the  2.4
widths used by multiplying  by 2.4 instead of  2.5.  This will make  words
with these characters slightly  cramped, but won't  effect the spacing  of
the rest of the document.  Or the characters could be spaced correctly  if
the space between words is shortened.

The next three fields, the designsize, interline spacing and space  width,
are included to enable one to use the font to print listings.

The designsize  is  the generic  size  of the  font.   It also  tells  the
distance between baselines and is used to make listings.  An N point  font
normally has  N/72  inches  between  baselines.   The  width  of  a  space
determines the size of  spaces and tabs.  The  purpose of including  these
numbers is  not to  encourage low  quality type-setting,  but to  make  it
easier to print nicer listings with multiple fonts.

The interline spacing distance field  may differ from the designsize.   In
proper fonts they should be identical,  but often fonts look different  on
different devices.  The interline spacing is a subjective spacing based on
the look of text.  MetaFont does not know about interline spacing, but  in
the Rst files it generates, sets this field to 1.2 times the design  size.
This may be changed by someone with a font editor.

[explanation of rotation and advance dir's]

The  rest  of  the  fields  are  present  to  encourage  correctness.    A
verification program can check that a font's file name corresponds to  its
contents.  A device dependent program assembling text can ensure the  font
was made for it, or at least for a printer of its resolution.  A user  can
find out who made a font in case it needs to be improved.

Directory and Rasters

DIRECTORY:
Each glyph in the font has an entry in the directory.  Each entry takes up
15 bytes, thus the directory occupies 15 bytes times the number of  glyphs
in the font.  A glyph  is defined in the font  if its character number  is
between the first and last character  numbers (inclusive) as given in  the
preamble and has a non-zero directory entry (described below).

Let FG be the character number of the first glyph in the font file, let LG
be that of the last glyph, and let DirPtr be the pointer to the first byte
of the  directory as  given in  the  preamble.  Then  the address  of  the
directory  entry,  DEaddr, for  character N,  assuming  (FG ≤ N ≤ LG)  is:
DEaddr ← DirPtr + ((N-FG)*15).

In a given directory entry, the bytes are:
#bytes info description
    2	H:  height (in pixels) of raster picture.
    2	W:  width (pixels) of raster picture.
    2	Y:  distance (pixels) from the top of the raster array to the 
		glyphs's reference point.
    2	X:  distance (pixels) from the left of the raster array to the
		glyph's reference point.
    4	FW: advance width of the character, in FIXes.  Note that this is
		a signed quantity (see page 3).  The advance width is
		also called the printing width or nominal width.
    3	P:  pointer to raster data (absolute byte address with the first
		byte of the file having address 0 (zero)).

H and W  are the height  and width in  pixels (bits) of  the raster  array
containing the glyph.  The glyph is stored  as a sequence of H rows,  each
row being (W+7)%8 bytes long ("%" is truncating integer division).

A character has a reference point often near, or just left of, its center.
Y and  X are  the distances  from the  top left  corner to  this point  in
pixels.  Both  of  these numbers  may  be negative,  in  two's  complement
representation.  For the  y-coordinate, positive is  downward, for the  x,
toward the right.

FW is the  advance width  of the  character in  FIXes.  This  is a  signed
quantity.  Remember to multiply this width times the magnification to  get
the true physical width, in FIXes.

The final value contains  a pointer to the  character's raster picture  in
the data section.  The pointer is an absolute byte address; the first byte
of the file has address 0 (zero).

Let BW be the width of the character in bytes (= (W+7)%8).  All rows start
on byte boundaries and are packed to the  left, so the last byte in a  row
will not be fully used unless the width of the character is a multiple  of
8.  So the entire glyph's picture takes up BW*H bytes.

At Sail and Score, computer words are 36 bits long.  On these systems four
bytes are stored per word  in the high (left) 32  bits of each word.   The
rightmost 4 bits contain zero.

    More on the directory and bit representation- needs update

Again, the pixel height and width have no connection with the 'height' and
'width' that TEX  thinks the character  has (from the  TFM file);  rather,
they are the size of the smallest bounding box that fits around the  black
pixels that comprise the character's raster representation.  For  example,
here is a letter "Q"  from some Rst file.

 0  ----**** ***----- -.......
 1  ---***** ****---- -.......
 2  --****-- -****--- -.......
 3  -***---- ---***-- -.......
 4  ****---- ---****- -.......
 5  ***----- ----***- -.......
 6  ***----- ----***- -.......
 7  ***--*** **--***- -.......
 8  ******** **-****- -.......
 9  -*****-- ******-- -.......
10  --****-- -****--- -.......
11  ---***** ****---- -.......
12  --X-**** ***---** *.......
13  -------- ***--*** -.......
14  -------- -*****-- -.......
15  -------- --***--- -.......

    76543210 76543210 76543210
    Bit Number (high order bit is #7)

There are 16 bytes in the font marking, maybe 56 in the preamble, and 9*15
directory bytes before Q's, so if the first byte of the file is numbered
zero, the directory for Q is in words 207:221, inclusive.

directory entry, values of each byte are in octal:
 53) 000 020 		← pixel height of rastor data (16)
     000 021 		← pixel width of rastor data
 54) 000 014 		← pixel y offset
     000 002 		← pixel x offset
 55) 000 125 142 131	← number of fixes in printing width = 18 pixels
 56) 000 001 420	← where in the file the rastor data starts

(The rows  and  columns are  numbered,  and  the reference  point  of  the
character is marked with an X, but only the stars and dashes are  actually
part of the character--stars represent black pixels, and dashes  represent
white pixels.  Periods represent zeros that are not part of the character,
but fill the bytes.  Bytes are separated by a space.)

Note that the Pixel Width is  just large enough to encompass the  leftmost
and rightmost black pixels in  the character.  Likewise, the Pixel  Height
is just large enough to encompass the topmost and bottommost black pixels.
So, this Q's Pixel Width is 17 and its Pixel Height is 16.

Here the offsets are the distances from the bounding box's top left corner
to the 'x' in the picture.  The X-Offset is 2 and the Y-Offset is 12.  The
offsets of a character are positive  if the reference point is inside  the
bit map (or below it and to its right).

There are 26 characters in  our font, but they need  not be in order.   If
metafont made the letters from Z to A,  then Q is the 10th letter.  At  an
average height of 15 or 16, the pointer  to the bit raster may say its  at
byte 1102, 16 for the  font marker, maybe 56  for the preamble, 26*15  for
the directory plus about 160*4 for the rasters.

    Still more...

Bytes 8-11 in  a glyph's  directory entry contains  the TFM  Width of  the
character.  This  is the  width  that TEX  thinks  the character  is  when
printed (exactly as in the  .TFM file) in units  of FIXes.  The TFM  Width
does not take  into account the  magnification at which  the VNT file  was
prepared and is completely independent of the glyph's pixel width.

Thus, if "Q" had a TFM width of  5620393 fixes, it would print at a  width
of 5620393 fixes  / (2↑20 fix/pts)  / (72.27 pts/inch)  * 240  pixel/inch=
17.8 pixels which would  be rounded up  to 18.  This is  a font about  5.4
points high.

If this  font  was  made  from  a  font  10.8  points  high  and  thus  at
magnification .5 (one half), then the TFM width would have been  11367088,
twice as much as before, and  only by multiplying it by the  magnification
(.5) would one get the actual printing width.

Below is a the same letter Q  with raster dimensions 16 pixels high by  17
pixels wide, showing the set bits in each byte.  Note that the byte  width
is 3 (17+7=24, 24%8=3) in order to accommodate the rightmost pixel in  the
third row from the bottom.

1102 00001111 11100000 00000000
1105 00011111 11110000 00000000
1108 00111100 01111000 00000000
1111 01110000 00011100 00000000
1114 11110000 00011110 00000000
1117 11100000 00001110 00000000
1120 11100000 00001110 00000000
1123 11100111 11001110 00000000
1126 11111111 11011110 00000000
1129 01111100 11111100 00000000
1132 00111100 01111000 00000000
1135 00011111 11110000 00000000
1138 00001111 11100011 10000000
1141 00000000 11100111 00000000
1144 00000000 01111110 00000000
1147 00000000 00111000 00000000

    76543210 76543210 76543210
    Bit Number (high order bit is #7)
 

Naming font files, Other Programs and Sources

SAIL
At Sail, Rst files  for the ImPrint-10 reside  on CAN,SYS, and have  names
<name>.R##.  Here the name is something like cmb10 or cmr13 and the ##  is
a  two  digit  number   between  0  and  100   specifying  10  times   the
magnification.  For instance, "cmr10.v20[can,sys] is  an Rst file for  the
ImPrint-10 containing  a cmr10  font at  magnification 2.0.   Most  likely
MakImp will not substitute fonts too  freely if the desired font does  not
exist, but some magnifications will be well represented.  Of course a user
specified Rst on  a different directory  can also  be asked for  in a  DVI
file.  In this case only the exact filename will be sought.


Other Programs and Sources

    RdRst produces an editable Asc ascii file from an Rst file

    AscRst does the opposite- unfinished- in pascal

    Sail sources for these programs are in a spindle file RstSrc.spi[can,sys].
	.READ SPINDLE for information about retrieval.
    Some of the files may be on [can,sys] with the extension .RAD